The version of Open Prolog to which this document refers is given in the Get Info… information for this document.
• Open Prolog Extras
Some of the useful external predicates in Open Prolog are listed below.
Check for the existence of these predicates as described in Open Prolog Info -
it's always possible for the documentation to be out of date.
Mail us if you see something you can't understand or use - that way,
we might fix the documentation…
• Multiple Choice
• An external predicate has been added: 'system$multiple$choice'/15.
It is also presented as a sample external predicate, written in MPW pascal.
'system$multiple$choice'/15 presents a dialog containing an OK button, an optional second button, an optional message and up to five edit boxes, each with its own prompt.
If the SecondButtonNameAtom is '', then the button doesn't appear.
The MessageString and the PromptStrings and ReturnStrings are all lists of integers, each integer being the ASCII of the character (useful for parsing with DCGs).
If a PromptString is [] (i.e. nothing) then neither it nor its corresponding edit box will appear on the dialog. Thus you can control the number of multiple answers available.
Here is an example:
'system$multiple$choice'(
'Sample Dialog…',
"This is a sample message",
'Oui',
'Non',
ReplyAtom,
"Prompt for a string here",Return1String,
"",Return2String, %invisible second choice
"…and here too…",Return3String,
"",Return4String, %invisible fourth choice
"…finally, here.",Return5String).
• Menus
◊ Adding & Manipulating Menus
To add a menu, or to change an existing menu, use the following call:
%a MenuItemName of '' will not add anything to the list of the menu's items, but will add the menu to the list of menus if necessary.
%always use 'set' or 'delete' for the first argument.
%enter 'standard' or 'hierarchical' for the kind field.
%Enter 'enabled' or 'disabled' or '' in the Enable field.
%Enter Icon Number or 0 in Icon Field
%Enter character code for Keyboard Equivalent in KeyEquivalent Field (only works for a new menu).
%Enter character code for Marking Character in MarkChar Field.
%Menu Number & Item Number are returned.
'system$menu' can be used to enable & disable existing menu items.
The system adds 256 to the icon number you provide, if it's not 0.
(Supply your own icons using something like ResEdit.)
example:
J is "",K is "Y",'system$menu'(set,'Trixi','First Menu 2',standard,enabled,1,K,J,Menu,Item).
SUGGESTION - set the font for this window to Chicago (the standard menu bar font), and experiment with different values for J above (look in KeyCaps for reference - e.g. control-R gives the tick mark ).
When the menu is selected by the user, Open Prolog looks for a clause
with a head of the form:
'system$menu$hook'(MenuName,MenuItemName)
If it is found, the clause is executed.
° Hierarchical Menus
The Command Key field and the Mark Char field are re-used to implement hierarchical menus. To hook up hierarchical menus, the Markchar number of the menu item that points to the hierarchical menus must be the same as the hierarchical menu's Menunumber. So, you can define the hierarchical menu items first, getting back the menu's menunumber; then define the menu item that points to it as a hierarchical menu pointer (by making its command character number 27), and 'hook it up' to the previously defined hierarchical menu by defining its markchar number to be the same as the hierarchical menu's number. Complicated huh?
Notice that when a hierarchical menu item is selected, it is the *menu's* name and the menu item name that are returned - see the example below.
Here's an example that also demonstrates the 'system$menu$hook'. Select it all and press the ENTER key:
If the MenuItem is '', the whole menu is deleted. Be careful about deleting the standard menus - they are linked to Open Prolog by position, not by text or appearance.
For some special purposes, you may wish to delete the Prolog menu; that's fine, but you'd also be deleting the command-(.) menu item which is used for stopping wayward program execution. You can redefine the command-(.) menu item to suit your own purposes, as long as you make sure its command key equivalent is the dot.
• Status Bar
The status bar is available to your program as a convenient display for the state of your program. Users are happier when they know something is happening. The rotating cursor indicates that Open Prolog is running, and you can get your program to display ongoing information on the status bar.
There are three resources available to your program:
(1) The status box at the extreme left - normally it contains the prompt ?- but it may contain 'Running…' 'Results…' 'mm' or 'gc' indicating different activities (mm means memory management, gc means garbage collection). The debugger uses it as well. You can use it yourself without interfering with these other uses of it.
(2) The message box, from the right hand side of the window leftwards. This may contain a larger string of text than the status box.
(3) The progress indicator. This is a 'thermometer' - a rectangle in which you can set the fraction of it showing gray. For example, you see this a file is being consulted or reconsulted.
You can push, set (i.e. change) or pull messages to or from the status and message boxes, and you can show, hide and set the progress indicator.
'system$set$progress'(A,B). % set gray part of thermometer as a fraction of the rectangle equal to the ratio A/B. A and B must be integers.
Previous values of A and B are lost.
Note: if your application's execution is characterised by processing a file, then by using the 'system$get$file$size' and 'system$get$fpos' predicates (see below) in conjunction with the progress indicator, you can give the user an idea of how much progress is being made. Here is an example where calls to the get0 predicate could be replaced by get0WithProgress:
get0WithProgress(X) :-
seeing(user),!, %don't display for input from the user…
play(SoundName,Volume) will play any Type 1 'snd ' resource.
Sounds recorded with the ‘Sound’ Control Panel Device and
all the sounds for the System Bell are snds of this type.
To play them, give their names exactly as they appear in
the ‘Sound’ Control Panel Device.
Be careful to get spacing and punctuation exactly right.
If the sound can't be found, or is too big to fit into memory,
the call will fail,
Pass a Volume of 0 - 7. A volume of 0 means the current sound volume control setting
will be used.
E.g.
play('Simple Beep',5).
The snd resources can be resident in any open window, the Worksheet,
Open Prolog itself, or the System.
Speech Manager predicates.
Two predicates are available: speakAtom/1 and speechBusy/1.
They both need the Speech Manager to be present and will throw error codes if it is not.
speakAtom/1 takes its atom and speaks it. You have no control over any of the parameters of speech. As soon as the command is sent to the Sound Manager, control returns to Open Prolog, which can then process while the speech is being uttered. If you execute another speakAtom, the previous speech will complete before the command is honoured.
speechBusy/1 unifies its argument with the number of speech channels busy. If there is no speech, the number of channels will be 0.
These are external predicates, and the code for them is given in the External Predicates… Folder.
• Low Level Debug
macsbug & macsbugFail need Macsbug to work, and will crash otherwise.
%returns in FileSize the size of FileName in bytes. (Normally one character occupies one byte.) An ErrorNumber of 0 is OK, anything else is a problem. Note that it isn't necessarily possible to open the file.
These are the characters returned by get or get0 for an end-of-line condition of an end-of-file condition, chosen for compatibility with DEC10 Prolog.
• Window-handling Predicates.
A number of predicates have been written to handle window-based I/O.
Please be aware that they are subject to change.
Basic Ideas:
° Window Numbers
We use window numbers because it is not possible to refer to a window by its name. This is because its name may change, and because (in theory anyway) many windows could have the same names.
So, every window is assigned a window number when it is created (distinct from its parameter pointer or file number etc.).
° Starting Pointer & Single-Line-Selection
Whenever text is output to a window (say using the write command), a pointer, called the Starting Pointer, is made point to the next character after the last
character output.
When a user selects text using the ENTER key, the text selected goes
into a text buffer that is passed to the Prolog interpreter.
In the case of single-line-selection, the start of the selection is found by going from the caret backwards along the line to the start of the line or to the Starting Pointer, whichever comes first. The end of the selection is the end of the line.
° Highlighting & Outlines
It is possible to highlight a particular run of text. Just to confuse you,
the highlight is called an outline, because that's how it started out.
The highlight will 'stick' to the text specified even when text before,
within or after it has been added or removed. Therefore it's not safe to
refer to a highlight by its start & end points, which may vary. Instead, a
highlight is given a unique index number by which it may be referred to
These can be used to get and set the starting point. Normally you needn't
bother with these, as the starting point is automatically updated.
Sometimes, however, you 'll need them. For example, say you've written
a parser, and you want to indicate errors to the user in the window.
When you display the error message as appropriate, you'll want to
reset the window environment just as it was just before
the error occured. For this, you'll need to get the Starting Point beforehand,
and then reset it after outputting the error message, etc.
I have a rather complex example, so mail me if you'd like it.
'system$window$front'(WindowNumber).
Tells you which window is at the front.
'system$window$get$output'(WindowNumber).
Tells you which is the current output window.
'system$window$set$output'(WindowNumber,Status).
The designated window becomes the output window. Any error (e.g. if
the window is read-only, etc. will be reported in Status. A Status of 0
means OK.
'system$window$select'(WindowNumber).
Bring the window to the front.
•Note, in the following, where Start and End character offsets are mentioned, character numbers start at 0. The range from start to finish is inclusive of the starting character and exclusive of the ending character.
